feat(contracts): M002 legacy seller claims migration - #982

Summary

Adds M002, the migration that enables claims from the deployed AntseedSellerRewardsPool after M001 activates.

The intended release is 10% of cumulative locked rewards (1000 bps) for eligible sellers, and zero for proven wash traders. There is no vesting and no manual owner-managed eligibility list.

M002 removes both existing claim blockers:

• Deploys and installs AntseedLegacySellerClaimPolicy using the pool owner.
• Whitelists the pool on ANTSToken using the token owner, allowing payouts while general token transfers remain disabled.

Claim rules and accounting

• The policy uses the required, immutable wash-trading registry's isProvenWashTrader(seller) result. Flagged sellers receive zero; their rewards remain locked.

• The release percentage is immutable after deployment; the installer defaults to 1000 bps (10%). There is no time-based vesting.

• The policy is stateless because the pool calls it as a view. It reconstructs cumulative rewards from V2 claim flags plus V2/V1 points, scanning epochs 0 through lastEpoch, including applicable pre-migration claims through V2. Earned points alone do not create a withdrawal entitlement.

• For ordinary pool sellers, alreadyReleased = cumulativeRewards - currentLockedBalance. The policy returns the remaining lifetime allowance, capped by the actual locked balance:

  allowance = floor(cumulativeRewards × releaseBps / 10_000)
  claimable = min(currentLockedBalance, max(allowance - alreadyReleased, 0))
  

• The pool reduces its stored locked balance after every withdrawal. Claiming again, choosing another recipient, or waiting longer cannot unlock another 10% of the same rewards.

• Sellers with unclaimed legacy emissions initially receive only the allowance supported by rewards already locked. After claiming additional eligible legacy emissions into the pool, they can withdraw only the additional released share.

• DIEM has zero locked rewards and cannot claim from the pool. The policy returns zero immediately for a zero locked balance; DIEM's historical direct payouts do not create an M002 withdrawal entitlement.

• The policy has no owner, manual wash-trader flags, or mutable registry setter. Existing external administrative powers, including the pool owner's ability to replace the whole policy, are unchanged. Mixed future direct/locked histories remain unsupported.

Implementation

• policies/AntseedLegacySellerClaimPolicy.sol: immutable configuration, registry-based wash exclusion, and cumulative release accounting.
• script/migrations/M002LegacySellerClaims/Install.s.sol: keyless, idempotent installation; guards M001 activation, discovers the pool through V2, derives lastEpoch = gate.effectiveEpoch() - 1, and requires a nonzero wash registry with deployed code.
• scripts/deployments/m002.mjs: installation state inspection, deployment-ledger recording, crash recovery, and fork-rehearsal integration. Defaults the wash-registry address from M001's pinned configuration.
• M001/ledger helpers support reusable fork rehearsals and prevent temporary rehearsal ledgers from regenerating repository chain configuration.
• Updates README/runbook documentation, .env.example, and CHANGELOG.

Validation — September 8, 2026

For current PR head 7ca6055f0efe34de8b185c625a98706d301d6a44:

• 33 focused Solidity policy/migration tests passed.
• 57 deployment CLI tests passed.
• Earlier full-suite counts are not presented as a fresh full-suite run for this revision.

Additional local mainnet-fork validation (not yet committed or pushed)

The local fork suite, fixture, seller inventory, and detailed report are not yet part of this PR. These results exercise the current policy against actual deployed Base contracts and wash-trading state at block 51,048,693, with M002 installed only in the simulation. No mainnet transactions were sent.

All five M002-specific fork checks passed:

1. Reconciled 201 discovered sellers, including 82 existing pool depositors, against historical deposits and current balances.
2. Tested exact initial payouts, immediate repeat claims with different recipients, and replay after one year.
3. Tested 644 unclaimed seller/epoch pairs, including incremental locking and withdrawals, duplicate epoch IDs, and repeated V2 submissions.
4. Tested batch legacy claims and cumulative withdrawal limits.
5. Tested DIEM's zero pool entitlement, replay rejection, and inability to forge locked rewards.

The real registry flags 54 sellers, including 34 existing pool depositors, who receive zero. The 48 eligible existing pool depositors have a combined initial allowance of 1,001,790.830220823917019615 ANTS. Future epoch-21 amounts remain dependent on usage before finalization.

Separate DIEM diagnostic finding: four additional local checks fail due to pre-existing downstream staker accounting, not M002 pool eligibility. Already-finalized DIEM liabilities exceed its balance by 1.580730664447246959 ANTS; including epoch 21 at frozen snapshot usage produces a 1.780069019657685820 ANTS shortfall. Payouts fail identically without M002 or the M001 registry flip. This requires separate remediation and does not give DIEM access to the locked-rewards pool. The combined focused/local run is 38 passed, 4 failed, not an all-green suite.

The direct contract-level fork checks are not a completed end-to-end deployment-CLI rehearsal: this branch's older M001 guard expects zero points policies, whereas the newer deployed configuration has one. The fork performs the authorized cutover actions directly. The current full CLI rehearsal remains to be validated against the matching M001 tooling before broadcasting.

Usage

pnpm contracts:deploy -- M002 --network base-mainnet --fork-test
pnpm contracts:deploy -- M002 --network base-mainnet --dry-run
pnpm contracts:deploy -- M002 --network base-mainnet --broadcast \
  --signer deployer=account:antseed-owner \
  --signer sellerRewardsPoolOwner=account:antseed-ops

Before broadcasting, resolve the deployment-tooling compatibility noted above, verify the intended 1000 bps configuration and wash-registry address, and follow the M001 cutover ordering, including funding any required DIEM legacy reward pots before changing emissions routing.